// ==================================================================================
// Shared Genomics Project MPI Codebase
// Version 1.0 30/04/2010
//
// (c) 2010 University of Manchester all rights reserved
//
// This file is distributed under the GNU General Public License, Version 2.  
// Please see the file COPYING.txt for more details
// ==================================================================================

#ifndef _CHROMOSOMES_H_
#define _CHROMOSOMES_H_

#include "types.h"

#ifdef __cplusplus
extern "C" {
#endif

/*!
\file
\ingroup	gio
\brief		Chromosomal %Model Header File */

/*!
\brief	Structure defining the chromosomal model of a species.
\details 
	A chromosomal model is defined for a particular species.
	Chromosomal defined as an array and the primary mechanism of associating a SNP to chromosome is via an index (i.e. chromosomal number).
	This code follows the numbering scheme favoured by both PLINK and the NCBI dbSNP.
	At the moment only define the human CHR model.
	If a SNP does not have a CHR number, it is bound to CHR-0 by default and assumed to be a diploid.
*/
struct chromosomes {
	/*! \brief Number of chromosomes in the model. */
	int n;

	/*! \brief Flags if model is defined */
	BOOL isdefined;

	/*! \brief CHR ID Strings. 
	\deprecated Not used
	*/
	char **chr_map_keys;

	/*! \brief The chromosomal number of a ID string index. 
	\deprecated Not used
	*/
	int *chr_map_values;

	/*! \brief No. mapped CHR ID strings 
	\deprecated Not used
	*/
	int nMapValues;

	/*! \brief Boolean array flagging if chromosomal number is haploid. */ 
	BOOL *chr_haploid;

	/*! \brief Boolean array flagging if chromosomal number is autosomal or not. */ 
	BOOL *chr_sex;

	/*! \brief Boolean array flagging if chromosomal number is on male 'Y' chromosome. */ 
	BOOL *chr_Y;

	/*! \brief Array of 'formal' CHR identifier codes. 
	\deprecated Not used
	*/ 
	char **chr_code;
};

/*! 
\brief Initialise the chromosomal model.
\details All pointers set to NULL, all numbers set to zero.
\param [in, out] chr Pointer to chr model
\returns 1 on success, 0 on failure.
*/
int chromosomes_init(struct chromosomes *chr);

/*!
\brief Allocate storage for the CHR attribute arrays.
\details 
	The size of the model must be defined (see \ref chromosomes::n) 
	and the model initialised (see \ref chromosomes_init).
	If a model is already defined, this function will fail.
\param [in, out] chr Pointer to chr model
\returns 1 on success, 0 on failure.
*/
int chromosomes_alloc_attributes(struct chromosomes *chr);

/*!
\brief Free the CHR attribute arrays.
\details The freed pointers are set to NULL.
\param [in, out] chr Pointer to chr model
\returns 1 on success, 0 on failure.
*/
int	chromosomes_free_attributes(struct chromosomes *chr);

/*!
\brief Define the human chromosomal model.
\details Fails if model already defined.
\param [in, out] chr Pointer to chr model
\returns 1 on success, 0 on failure.
*/
int chromosomes_define_human(struct chromosomes *chr);

/*!
\brief Binds a CHR ID string to a chromosomal number.
\param [in] key CHR ID String
\param [in] index CHR Number to bind ID string to.
\param [in, out] chr Pointer to chr model
\returns 1 on success, 0 on failure.
\deprecated Not used
*/
int chromosomes_make_pair(const char* key, int index, struct chromosomes *chr);

/*!
\brief Finds a CHR number with a CHR ID string
\param [in] key CHR ID String
\param [in, out] chr Pointer to chr model
\returns chromosomal number (zero to n-1) or -1 on failure.
\deprecated Not used
*/
int chromosomes_find(const char *key, struct chromosomes *chr);

#ifdef __cplusplus
}
#endif

#endif // _CHROMOSOMES_H_
